Almathera Ten Pack 3: CDPD 3

home *** CD-ROM | disk | FTP | other *** search

/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 151-175 / scopedisk152 / atree / atree.doc < prev next >

Wrap

Text File | 1995-03-19 | 66KB | 1,327 lines

ATREE Professional Version 2.0 Copyright 1990 by Delta Software Associates All Rights Reserved To print Atree.Doc, at your CLI prompt enter: "type > prt: atree.doc", and press the RETURN key. This version of Atree is much improved over the previous version. Many bugs have been removed, improvements made, and options added. This version is not fully functional -- it contains options that do not work. Options that do not work will present a requester indicating that you are not registered. You may obtain a fully functional version of Atree for $40.00 (U.S.). You will then be entitled to upgrades as they are released. Send cash, check, or money order to: Delta Software Associates P. O. Box 690863 Stockton, Calif. 95269-0863 Atree has no warranty or guarantee. The author assumes no responsibility whatsoever for any effects, good or bad, that Atree may have on hardware or software. ************************************** About Atree: ************************************** Atree is a disk utility which imitates similar utilities widely available on IBM compatibles (PC Tools, XTree, QuickDos, etc.). The intent is to allow the user a graphic representation of the entire (or any portion of the entire) directory structure on a disk device, including the files in each directory, and the capability of moving quickly through the "tree" to a directory to access its files for purposes of copying, deleting, moving, viewing, editing, executing, etc. Atree is intended to be a reasonable substitute for both the Command Line Interface and Workbench. It is a platform from which you can easily enter AmigaDos command lines or locate and select files for execution, copying, moving, deleting, viewing, reading, etc. It is a disk/file management system that allows quick and easy viewing and changing of a disk's directory and file organization. Because of the graphical nature of the user interface, using the mouse to visually move through a disk's directory and file structure is easier than using the CLI commands "cd" and "dir" and is more enlightening than using the Workbench -- with Atree, you clearly see where you are in a disk's organization of directories and files in relation to other directories and files. And you can move from one to another far more quickly and with less effort (fewer mouse clicks and moves) than with Workbench. Atree currently supports and will read into memory a directory tree that has a maximum depth of 65536 directories and no more than 65536 subdirectories total for the entire tree. (This is because Atree currently supports a spreadsheet type matrix of 65536 columns, each column representing the subdirectories of a parent directory and 65536 rows representing a directory with the first of its children directly to the right of it, and only a total of 65536 rows currently supported). It is not known how the program will behave if the total number of directories in a tree exceeds 65536 or if the depth of the tree exceeds 65536 generations. Although Atree can support a maximum depth of 65536 directories not to exceed 65536 directories total in all directories for display purposes, it can only support a maximum depth of 512 directories for purposes of deleting, moving, copying, pruning, and grafting, or using any other function requiring a LOCK on a directory. Additionaly, there are more stringent limitations involved in the use of the "Replace from here" and similar routines (see the descriptions of such functions below under the "Tree Menu"). **************************************** Atree Instructions: **************************************** NOTE: If you are a first time user of Atree and do not have a file called "Atree.Config" in your s: directory, then running Atree will result in a requester indicating "Failed: Object not found" -- select "CONTINUE" and Atree will continue to load and initialize without problem. You should set up your config file during your first session; see instructions for the CONFIG menu below. If you are a user of a previous version of a Atree and are using this version for the first time, it is recommended that you delete or move the Atree.Config file from your s: directory and redefine your configs on your first run of this version. This version of Atree has an "Atree.Config" file accompanying it. If you wish, copy this file to your s: directory before running Atree. At least you will have some pleasant colors in your first session. ********************************************* Running the program. ********************************************* System Requirements: -------------------- Atree will run on the Amiga 500, 1000, and 2000. It requires at least version 1.2 of AmigaDos. Atree will self adjust to PAL and NTSC monitors -- PAL monitor displays should come very close to covering the screen and should display 15 files in the FILES box on the right of the screen; NTSC systems should only display 11 files. Atree uses the following fonts which the Amiga typically comes equiped with: Topaz 80 Ruby 8 Garnett 9 Opal 9 Ruby 12 Sapphire 19 These fonts must be appropriately placed in the directory path to which FONTS: is assigned. Atree will function without these fonts, and you may substitute your own fonts by renaming desired fonts per above. However, if the fonts are not of the correct dimensions, your various displays in which the fonts are used may look odd. NOTE: If you use ATREE to read large directory trees, as would likely be characteristic of hard disk drives, you may have to increase the stack size by entering the STACK command at the CLI prompt with an argument greater than 4000. A stack of 8000 should be quite sufficient. Atree Operates only from the CLI. The general format of the command should be: "run atree pathname pathname pathname ......". Examples: run atree df0: df1: dh0: ram: df1:utilities df1:pictures/flowers The above reads into memory six trees. The first four will be read from the ROOT directory of the indicated devices, and the last two will be trees read from the indicated subdirectories of the indicated devices. run atree dh1: dh1:c_sources dh1:c_objects The above reads into memory the three trees from the same device, dh1: The first tree will be the entire tree starting with the ROOT directory, and the second and third will be the subtrees starting with the c_sources and c_objects directories respectively. run atree df0: df0: df0: The above reads into memory the entire tree of df0: three times -- no good reason for doing it, but it can be done. run atree volume_1: volume_2: volume_3: The above reads the entire tree starting from the ROOT directory of three disks whose volume names are as indicated. The system will prompt you to insert the volume in any drive if not already inserted. A two drive system can thus be used to read into memory the directory trees of more than two disks and as many as the system's memory will support. run atree The above command line has no arguments and therefore atree will do one of two things: (1) If you have not previously defined any default paths for ATREE to read and have also not saved these paths to the Atree.Config file in the s: directory, you will be given a requester in which you must enter a path -- this path will be read into memory, or if you fail to enter a path you will exit ATREE, (2) if you have previously defined one or more default paths and have saved them in the s:Atree.Config file, then these paths will be read into memory automatically by ATREE. Reading into memory only the parts or sections of a directory tree may be the desirable course if you are using a hard disk that has extensive directories and you only intend to use two or more small portions of the entire tree. As many pathnames may be entered as the command line will support (Total of 255 characters). *********************************************** Getting Atree out of the Way *********************************************** Once Atree is up and running, you may want to get it out of your way. The Atree window is on its own screen. You may use the mouse pointer to grab the window drag bar and drag the window down a few millimeters. Then you can grab the screen drag bar behind it and move the screen down to the bottom of your display. You can also drag the window down to expose the screen's front_to_back gadget and click on it to put the Atree screen behind any other screens present. You can also put the Atree screen to the back of other screens by selecting the "Atree to back" item in the "Utils" menu. Atree can also be ICONIFIED. Select "Iconify" from the "Utils" menu and the program will be shrunk to a very small window that can be dragged or placed behind other screens. Click the mouse on the word "Atree" in this small window and the Atree program will be reactivated. *********************************************** Moving around in the directory and files: *********************************************** The currently selected directory tree is shown in a large box at the left of the screen under the word "DIRECTORY:". This box can be thought of as a window to a larger box containing the entire tree. The entire tree can be thought of as represented on a large spreadsheet with 65536 rows and 65536 columns. In this spreadsheet, a tree is formed which graphically represents parent, child and sibling relationships between directories. Children of the same parent (siblings) will all be in the same column; the parent of any directory is always in the column to the left, and the children of any directory are always in the column to the right. Line segments between directories show how they are related. The directory box at any moment displays up to five generations (columns) of directories, and up to sixteen rows. You may use either the mouse pointer in combination with the left mouse button, or the UP, DOWN, RIGHT, and LEFT arrow keys to scroll the directory "window" to display different sections of the whole tree spreadsheet, as explained below. To the right of the directory box is another box just under the word "FILES". This box lists up to sixteen files in the currently highlighted directory. You may use either the mouse pointer in conjunction with the left mouse button, or the shifted UP and shifted DOWN arrow keys to scroll through the entire list of files in the currently highlighted directory, as explained below. On the display screen, there will always be one directory and one file that are highlighted. The highlighted file or directory is understood to be the "argument" or "object" of the various commands you can select from the keyboard or menus. Only the first eight (8) characters of directory names are shown in the directory box; the full name of the currently highlighted directory is displayed to the right of the word "DIRECTORY:" above the directory display box. Only the first twenty-five (25) characters of file names are displayed in the FILES box. To see the full file name, select the RENAME/FILE option from the ATTRIBUTE menu. Cursor keys used alone move the highlighter in the directory box. Shift/UP Shift/DOWN move the highlighter in the files box. Click left mouse button on any legitimate directory or file and highlighter will move to it, skipping over anything between. Hold left mouse button down and move pointer -- highlighter will follow it. Clicking or holding the left button down with pointer close to the edge of either the directory or files boxes will cause display to scroll if there is anything to scroll to. The pointer with button held down functions according to the same rules as the cursor keys, no matter where on the edge of the screen the pointer is located. The position of the highlighter is what's important. Thus, if the highlighter is on a directory at the lower edge of the box and the directory has no entries in the same column below it, then no matter where you hold the pointer at the lower edge of the box, no scrolling will occur. But if you move the highlighter to a directory that does have entries in the same column below it, then no matter where you hold the pointer along the lower edge of the directory box, it will scroll. Atree also allows you to mark your place at up to three directories in any tree and to return to a marked place from any tree (See the description of the functions in the Directory Menu below). Tag files: Files in a directory can be tagged. The tagged files constitute a group that can be operated on as a unit for purposes of copying, moving, deleting, archiving, etc. To tag a file, move highlighter to file and press space bar (Directories can't be tagged). Once tagged, files remain tagged until an operation is performed on them. You thus may move to another directory to perform other operations and return later to the directory containing tagged files and the files will still be tagged. Tagged files are marked with the ">" symbol immediately to their left. You may remove the tag from a file by placing the highlighter over the file and pressing the space bar. Atree's numerous routines can be executed in three ways. All routines can be excuted by selecting the corresponding menu item from one of Atree's menus (See the section below titled "Using the Atree Menus"). Some routines can be executed from the keyboard (See the section below titled "Keyboard Operation"). And finally, some routines can be executed by selecting one of Atree's 44 gadgets (See the section below titled "Using The Gadgets"). ****************************************************** While Atree Is Working: ****************************************************** Many routines (copying. deleting, or moving file, for example) will cause Atree to display an alternate pointer that looks like like an "X". When this happens, it is to alert the user that Atree is busy and will not respond to commands. The pointer will return to normal when the routine is finished. The user then regains control of Atree. ****************************************************** Error Messages ****************************************************** Atree handles many error messages. There are error messages that are unique to Atree and these are explained in connection with the routines in which they will appear. Atree handles many but not all intuition error messages. When intuition invokes an error message which Atree does not handle, your Workbench screen will be brought to the front and the typical intuition requester will appear. Atree is still in your system and is still operational, but is in the background and you have to go looking for it. Atree allows the user to call on and execute with a command tail any program. If Atree is unable to successfully launch a program, the error will be handled either by Atree or intuition, depending on what kind of error was encountered. However, in many cases, the program may be successfully launched and encounter conditions which the program itself definces as errors. For example, if you launch the file compression utility, ARC, from within Atree using a command tail like "q stuff", ARC will generate its own error message. And ARC reports its errors to the CLI process from which it was launched which will be the same as the CLI process from which Atree was launched. Therefore, if a program or command of any kind launched from Atree does not appear to be functioning as desired, locate the CLI window from which you launched Atree to determine if an error message was written to it. Failing that, look for a special window, screen, or requester that the application may have established for the reporting of errors. ****************************************************** Using the Atree menus: ****************************************************** Tree Menu: ---------------------- Read next: changes the currently displayed directory tree by rotating through directory trees previously read into memory. Thus, if you have read into memory df0:, df1:, and dh0:, then selecting this option will cause the "next" tree to be displayed; "next" is determined by the currently displayed tree and the order in which the trees were read into memory, which, in turn, is determined by the order in which you entered the names on the command line. Get (replace): replaces currently displayed tree with a new one you specify. Get (new): reads into memory a new tree you specify and displays it. This will be a new tree in addition to the others currently read into memory. The user can thus read into memory a number of trees limited only by available memory after the program has been activated. Erase: Deletes the currently displayed tree. (You can't delete the last or only tree -- there must always be at least one tree). Info: Displays disk info, like how many bytes and blocks are free. Note that floppy 3.5 inch disks have 512 bytes per sector, but 24 of these bytes are reserved by the system. Therefore, the correct number of bytes usable by the user is 488 bytes per block multiplied by the total number of blocks available, and that is the figure used here. Also note that 512 bytes per block are usable if the FastFileSystem is used.. Show Memory: Displays total CHIP and FAST memory available. Set Max Depth: This option gives Atree some real flexibility. It allows the user to specify the depth to which any subsequently specified tree will be read from a disk. A depth of 0 means no depth is specified and Atree will read all directories it can. A depth of one (1) means only the subdirectories and files of the specified starting directory for the tree will be read. By specifying a depth of one (1), and by using a combination of the options "Replace from here" and "Add from here", the user can weave his way into a disk directory system one layer at a time. There may be a very real time savings by using this method. The current setting of the Max Depth variable is saved to the Config file described below. From that point on, Atree will use the setting in the Config file upon running the program. In addition, the functions "Read back (add)" and "Read back (replace)" allow the user to weave his way back out of a disk directory system. Replace from here: This option replaces the currently displayed tree with a new one that starts with the highlighted directory. Used in conjunction with a Max Depth setting, the user can penetrate only those portions of the directory that are of interest as an alternative to reading the entire tree. If the highlighter is already on the top (upper left hand corner) directory of a displayed tree, the operation will fail and yield the message "Tree already in memory". Add from here: This option functions the same as the "Replace from here" option described above, except that a new tree is created and becomes the displayed tree; the old one still remains. Read back (add): Allows the user to "back up" in a tree. For example, suppose you have just read your way into a directory such that your currently displayed tree represents everything from a depth of 15 to 18 from a particular directory and that your maxdepth for reads is set at 3. Selecting this option will cause the reading of a new tree. The new tree will be derived by selecting the parent's parent's parent of the old tree's top directory and use the path to that new directory as the basis for reading the newly added tree to a depth of three. In other words, from the top directory, we "back up" maxdepth levels in the top directory's direct line of descent and then read from that ancestral directory to a depth of maxdepth; in our example, we would end up with a depth of 12 to 15. If the maximum depth for tree reads (See the "Set max depth" option in this menu) is set to zero, this operation will fail and yield the message "Max depth = 0". Read back (replace): Functions the same as "Read back (add)" except that the new tree replaces the old tree. NOTE: The four options starting with "Replace from here" create a directory path string representing the complete path specification of the currently highlighted directory -- the tree is then read just as though the user had typed the path on the CLI command line on running Atree. The size of this string is limited to 2048 characters. These functions therefore can support a minimum depth of about 51 directories (if each has a 40 character name), and a maximum of about 1000 or so directories (if each is assumed to have a one character name). This should be quite sufficient for nearly all applications. Attribute Menu: ----------------------- Note: Allows FileNote on highlighted directory/file. Protection: Allows change of protection status on highlighted directory/file. (At present, ATREE allows the user to set the read, write, execute, and delete protection bits. The script, pure, and archive bits cannot be changed in this or any prior version of ATREE, but these bits are left undisturbed in copy and move operations. Rename: Allows renaming of highlighted file/directory. The very top directory of a tree cannot be renamed -- it represents a permanant anchor for your tree operations -- only directories in column 2 or subsequent columns of your display can be renamed. A future release of Atree will allow renaming of top directories. In all of the above cases, you can select the attribute from the menu to see or view the current specification and, if you wish, you can click on the string gadget to alter the current specification. Directory Menu: ---------------------- Delete: deletes all files in highlighted directory and deletes directory if there are no subdirectories. NOTE: This routine ignores delete protection -- the user must be sure that none of the files in the directory are wanted. Make: creates a subdirectory in the highlighted directory. Reread Files: Updates the memory list of files contained in the highlighted directory. This is intended to be used when you leave Atree to do some other work with other programs and change the composition of directories or the attributes of one or more files. This option will delete the current memory list of files in the highlighted directory and reread directly from the disk in order to achieve an exact correspondence between files in the directory and their representation in memory. Also, if you have specified a maximum depth for reads (see the "Set Max Depth" option in the "Tree" menu), you may end up with your last layer of directories showing in the directory display box, but any files contained in these directories will not have been read. You may use the "Reread Files" option to read only the files in these directories (subdirectories will not be read). These files will be incorporated in the list of all files in the currently displayed tree -- they will therefore be included in any subsequent use of routines in the "Sort" and "Locate" menus. (NOTE: the Configs menu, described below, has an option to set "reread" on or off for automatic use in some cases). Mark Destination: Highlighted directory becomes the target or destination directory for MOVE, COPY, and GRAFT functions. Any function requiring a target will not work unless a MARK is set. Show Destination: In case you have forgotten which directory in which tree you have selected, this option will tell you. You will however only get an abbreviated representation of the complete destination path specification; you will be given the name of your "tree top" (what you specified in order to read this tree) and the name of the directory that is marked as the destination (There may, of course, be more than one directory with the same name in a given tree, so be careful about your assumptions). The complete destination path specification is not given for the simple reason that Atree supports up to a depth of 65536 directories, each of which can have a name up to 40 characters long -- that represents a string of 2,621,440 characters! Goto Destination: Select this and your destination directory will be displayed and highlighted in the upper left corner of the display box. Place Mark: Atree allows you to set up to three place markers. The highlighted directory is marked so that it may be subsequently returned to from any tree or directory. Goto Mark: If a place mark has been set, selecting the goto option (1, 2, or 3) corresponding to it will cause the marked directory to be displayed and highlighted in the upper left hand corner of the directory display box. Prune: Selecting this option will delete all files and sub directories in the currently highlighted directory. The highlighted directory will also be deleted. This function is like cutting a complete branch from a tree. The function may not do a complete job of pruning if for any reason files and directories cannot be found or deleted. The prune function will, in other words, prune whatever it can. NOTE: The prune function will delete even delete protected files and directories without question or warning. Therefore, the user must make sure none of the files or directories in the branch to be pruned are wanted. For best results, the user should be sure that the memory copy of the tree's branch being pruned corresponds exactly to what is on the disk. As files in each directory are being deleted, if Atree is unable to delete any file, you will receive a requester asking if you want to abort operation. If you select "No", Atree will skip the file and try to delete the remaining files in the directory. If you select "Yes", Atree will skip the remainder of the directory and proceed to the next directory. Another type of error message you may get is "Failed: On attempt to lock". This means Atree was unable to get a system lock on a directory. Failure of Atree to delete files or obtain locks on directories may be the result of other programs running simultaneously which may alter the directory names, obtain their own locks, open files, or change file names. If these errors ore obtained during Prune or Graft (or for that matter most all other operations), you should attempt to reread the directory or tree, then attempt the operation again. Graft: This function copies what it can of the branch from the currently highlighted directory to the currently marked destination. The graft function can be used to copy an entire disk to a blank disk or to ajoin an entire tree to a marked destination in another tree or in the same tree. Tagged files: A requester will display the total bytes in all files tagged in the currently highlighted directory. Untag all files: Any files tagged in this directory will all be un-tagged. Quick path: This option allows the making of a directory "tree" consisting solely of the end directory of a complete directory path you specify. This directory is automatically made the destination directory for all subsequently selected file operations, thus overiding whatever was previously selected as the destination directory. To understand why this option is available and how it improves efficiency, suppose you were in a situation where you wanted to copy a bunch of files from the currently highlighted directory to a specific directory on a disk in df0:. One way of doing this would be to select "t" then "+" and specify your specific directory. Atree would then read in the entire tree from your directory up to the depth to which "max depth" is set (See explanation of "max depth" under the "Tree" menu). Doing this would cause Atree to then display your new tree and you would then have to set the desired directory as your destination. Then you would have to find your way back to the original tree you were in, locate the directory you previously had highlighted and then select the desired file operation. With the "Quick path" option, assuming you already have your source directory highlighted, you merely request "Quick path" and specify your path. Atree quickly reads in only the end directory you specified and marks it as the destination and leaves you in the highlighted directory. All you have to do now is select the file operation you want involving this new destination and away you go. Anytime later, you can find your way to this new tree to examine it or delete it from your system. File Menu: ------------------ Copy, Move and Delete highlighted, tagged, or all files in currently highlighted directories; choices should be obvious. NOTE: Copy and Move options will copy files despite any protection bits that may otherwise prevent copying. Additionally, the READ, WRITE, EXECUTE, DELETE, ARCHIVE, PURE, and SCRIPT protection bits are set in the destination to be the same as they were in the source file. It is intended that the MOVE operation will delete source files after they have been successfully copied to the destination directory, however, due to a bug, not all protected files are successfully deleted. This will be corrected in a subsequent release. Filenotes, if any, are also copied or moved. ATREE does not currently handle any protection bits other the ones mentioned above. The datestamp for a file may or may not be copied/moved, depending on whether or not the "Copy date" menu item is checked in the "Configs" menu. Archive: Use the Configs menu (see below) to specify the path to your favorite archive utility. Then select "Archive" highlighted/tagged/all from the FILE menu. You will be presented with a requester asking you to "Enter ARC arguments:". You should enter everything here that you want to be added to your path spec for your archive utility, except the filename -- this will be added automatically by Atree. The filename added by Atree depends on whether you selected highlighted, tagged, or all. To make the above clearer with an example: Suppose you entered "dh2:utilities/arc" as your path spec in the Configs menu for your Archive selection. Suppose you now select Archive/highlighted from the FILE menu. You get the requester asking you to enter arc arguments. Suppose you enter here, "a newarc". Suppose your highlighted file name is "this_file". What will happen now is that Atree will execute the command line: dh2:utilities/arc a newarc this_file For my particular version of ARC, the above command line will create an archive file, newarc.arc, in the current (highlighted) directory (if it doesn't already exist) and then will add "this_file" to it. Selecting "tagged" or "all" instead of "highlighted" will result in the above command line being executed over and over for all appropriate files. NOTE: at present, despite what your ARC utility supports, this version of Atree will not allow you to archive files whose names contain spaces. Thus, you can archive a file named "session1", but not "session 1". Execute: Executes the highlighted file with the RUN command; a command tail is requested via a requester and is optional. Text reader, editor, word processor, IFF displayer and sector editor should be obvious, but will not function unless first specified by selecting the "Paths" option from the CONFIGS menu. If specs are made in the CONFIGS menu, the program specified will execute with the RUN command and with the highlighted file as the command tail. Tag matching: If a pattern string has been specified via the "string" option of the "locate" menu, selecting this option will cause all files in the highlighted directory which match the specified string pattern to be tagged. User's Choice: Using the "User's choice" option of the "Configs" menu, you may specify the complete path for up to five programs you may wish to execute from Atree. When you run Atree for the first time, the five subitems of this option are listed as "??? Not Defined". Before these can have any meaning, you must first define these options by selecting one of the subitems under the "User's choice" option of the "Configs" menu. Speak: Selecting this option will cause ATREE to speak the highlighted file to you using the narrator device your system comes equiped with. The file so read should be an ordinary text file using ordinary ASCII. Do not attempt to read files prepared with word processors that employ embedded formatting codes within the file and do not attempt to read files that are prepared using the phonetic alphabet codes. The "Speak" routine actually calls the "Translate()" function in the narrator.device library to convert an ordinary ASCII string into a phonetic string before calling on the narrator.device to actually "speak" the string. The Speak routine uses the dafault system settings for voice rate, pitch, sex, mode, and volume. However, you may change these values by embedding appropriate codes within your text. The "\" character must be used at the beginning and end of a code sequence. Following the beginning "\", you use a "v", "p", "m", "s", or "r" to indicate volume, pitch, mode, sex, or rate respectively. These characters may be used in any order, but they must be followed by an appropriate numeric value as follows: v (for volume) must be followed by a value from 0 to 64. p (for pitch) must be followed by a value from 65 to 320. m (for mode) must be followed by 0 (natural) or 1 (robot). s (for sex) must be followed by 0 (male) or 1 (female). r (for rate) must be followed by a value from 40 to 400. If the volume, pitch, or rate values are above MAX or below MIN as indicated above, the speak routine will force the Max or Min settings to be set. As an example, if a text file contains the string, "\p100v30r320\", when the speak routine reaches this string, the voice will be set to a pitch of 100, a volume of 30, and a rate of 320 and these settings will remain in effect until changed again. The mode and sex settings are unaffected by the example string. A sample file called "voice.sample" should accompany this version of ATREE. Find this file and highlight it and select the "Speak" option from the "File" menu for a demonstration. There are certain rules which must be adhered to in preparing documents for the "speak" routine. First, the files should be in ASCII format (no embedded codes). Second, the unit of text that is translated is the "text string", defined as a string of ASCII characters terminated by the "newline" character. These strings should not be more than 256 characters long, including the newline. Third, the codes for changing voice settings ("\") should always be placed at the beginning of a string -- if placed elsewhere in the string, they will be ignored. Thus, any time you wish to change the voice, start a new line and enter the new codes first on that line, followed by the text you wish spoken with the new voice. Be especially careful that any text file you read does not contain a "\" character which is not followed quickly by another "\" character -- the speak routine will be thrown into an infinite loop and the system may crash. This danger is especially likely in C source code files that may contain "\n", "\t", or other escape codes. It is advisable to use the ATREE "Search files" routine to see if a file you are about to read contains any undesirable "\" characters before speaking it. If it does, you can use a text editor to search/replace with a harmless character, word or phrase before speaking the file. NOTE: It is obvious that the user may alter a directory tree or a file in many ways without the memory copy of the tree or file list being correspondingly changed. Therefore, through the use of text editors, word processors, archive utilities, etc. your memory copy of a tree as displayed by Atree at any moment may not correspond to the disk it is supposed to represent. The user is advised to update the tree by re-reading it using the "Get (replace)" option from the TREE menu. Use the same path specification as necessary to update your displayed tree to keep it in correspondence with the disk it represents. Alternatively, if you have only changed files in a certain directory, you may highlight that directory and select "reread" from the directory menu to just reread the files in that directory. Configs Menu: -------------------- This menu's options are used to change Atree's configuration, such as the screen colors, or the specified file reading utility you want Atree to use when you select "Text reader" from the "File" menu to read a highlighted file, or the default depth you want Atree to use when viewing a disk's directory organization. If you are using Atree for the first time, you should use the options below to configure Atree to your needs and then select the "Save" option. This will save to the s: directory the Atree.Config file that Atree needs to access every time it is executed. Paths: A requester allows user to specify a path leading to a text reader, editor, word processor, IFF display program, or sector editor (or of course any program specified). To use the requester set mouse pointer on selection, press left mouse button; if a specification was previously set, it will now appear in the uppermost string gadget at the top of the requester. If no specification was previously made, the uppermost string gadget will read "Enter path here". In either case, simply click on the string gadget and enter the desired path specification and press RETURN. When the corresponding selection is made via the FILE menu, the specified program will be executed with the highlighted file as the command tail. Thus, suppose you select "Text Reader" and in the string gadget you enter "dh2:utilities/blitz". When you now go to the FILE menu and select "Text Reader", Atree will execute the following command line: Run dh2:utilities/blitz <filename> where <filename> is the currently highlighted file. Selections which specify text editor, word processor, or archive utility do not execute with the RUN command. Set buffer: This is the read/write buffer for copying, moving, and grafting files -- settings above 512 or so are not too significant in terms of promoting speed, but you may set what you like. When using any of Atree's file searching routines, setting this buffer to values larger than 512 will significantly improve search speed. Save: Saves the currently specified paths to text reader, editor etc. Current colors are also saved (See "Colors" option below). The file, Atree.Config, is created in the directory specified by the s: assignment. If you are a first time user of Atree, and the Atree.Config file does not exist, you will get a prompt upon running Atree telling you "object not found" -- click on "continue" and the program will proceed with its initialization. Set up your config file per the above instructions for future running. The "Save" option will also save to the config file the currently specified "maxdepth" setting -- see the "Set max depth" option of the "Tree Menu" above. NOTE: the Utils menu (see below) has options for saving and reloading the currently specified configs (colors, etc.) to and from filenames you specify. You thus have unlimited config file capability. Your default config file which will always be looked for on running Atree is "s:Atree.Config". Check sp: Can be On or Off (Checked means "on"). If check is on, a check is made for sufficiency of disk space prior to any execution of copy/move/graft functions -- these routines will be aborted via a requester if there is not enough space for the file(s) to be copied to the device. Reread: If set to "on" (checked), highlighted directories will automatically be reread after invoking the word processor, text editor, or archive utility via Atree (i.e. from the file menu). Color Change: If checked, you will be able to adjust the currently selected color (see "Colors" below on how to make adjustments). If not checked, colors cannot be adjusted (prevents accidental color changes). Colors: This option allows you to select a color so that you can subsequently change it. After selecting a color with this option, you can change the color by placing the mouse pointer over one of six small areas located at the bottom of the Atree main display screen and clicking or holding down the left mouse button. The six sensitive areas are defined below: FUNCTION SENSITIVE AREA DEFINED BY Increase RED component: The words "File size:" Decrease RED component: The word "Directory:" Increase GREEN component: The upper word "Protection:" Decrease GREEN component: The lower word "Protection:" Increase BLUE component: The upper word "Date:" Decrease BLUE component: The lower word "Date:" The current settings of all colors are saved in the Atree.Config file each time the "Save" option of the "Config" menu is selected. User's choice: You may define up to five programs to be executed with an argument string you specify each time the program is run plus the currently highlighted file. You can specify whether or not the program you select is to be executed with the "RUN" command. To make this clear, suppose you have a file searching utility called "search". Suppose the path to this file is dh2:utilities. Suppose also that there are several switches and search strings that you can specify for the search and that these switches and strings are to be specified after the executable filename (search) but before the file to be operated on (the currently highlighted file). Thus, you may wish to execute the command line: search -abcdef "search string" highlighted.filename It is precisely this pattern of execution that these "User's choices" are aimed at satisfying. To set up the above example, you would select one of the subitems from the "User's choice" option of the Configs menu. You will be presented with a requester asking you to enter a menu subitem name. The name you enter here is arbitrary and will appear subsequently in the "File" menu, "User's Choice" subitem, to serve as your reminder as to what this selection is all about. You may enter anything you like here. "Search" would be a good idea. You will then be given a requester that asks you for a path specification. Here you would give the complete path specification for your "search" program, thus "dh2:utilities/search". You will now be asked via a requester if you wish to execute this program with a "RUN" command or not. This is explained below. You may click on "YES" or "NO". Your definition of a User's choice is now done. If you now go to the "File" menu and select the "User's Choice" option subitem you just defined ("Search" in this case), you will be presented with a requester asking for arguments. You may now enter your arguments, -abcdef "search string", in this case. Now, one of two command lines will be executed: either: RUN search -abcdef "search string" highlighted.filename or: search -abcdef "search string" highlighted.filename Just which line is executed depends on what whether or not you requested to execute the program with the "RUN" command. Many programs take command line arguments as described above. These user options thus can be very useful and make your life a lot easier when using Atree. One question remains. When do you opt to use or not to use "RUN"? When you execute a program with the RUN command from within Atree, Atree immediately regains control and can continue on. When you execute a program from within Atree without the RUN command, Atree will stop dead in its tracks until you quit the program you ran (or it finishes by itself). The simple criteria to guide you is this: don't use the RUN command to execute a program that may change or alter any files that Atree itself may gain access to -- try to do otherwise and you will (probably) be visited by various GURUs. Format: Use this option to set the parameters for the format option you select from the Utils (utilities) menu (See below). You can select one of four drives (df0: thru df3:) for formatting. if ICONS is checked, formatting will result in the usual icons being placed on the formatted disk; if QUICK is checked, it will be assumed that your disk is already formatted and it will only be initialized; if FRONT is selected, the WORKBENCH screen will be brought to the front so you you can see the CLI window from which Atree was run -- this is where any status and errors from the format program will be printed. All of these settings will be saved to the Atree.Config file each time "save" is selected from the Configs menu. The "format" command file must be present in the c: directory. From dev: This option specifies the disk drive to be used as the FROM device in the DiskCopy command accessible via the DiskCopy option of the Utils menu (see below). The "DiskCopy" command file must be present in the SYSTEM: directory. To dev: This option specifies the disk drive to be used as the TO device in the DiskCopy command accessible via the DiskCopy option of Utils menu (see below). The "DiskCopy" command file must be present in the SYSTEM: directory. Copy date: If this menu item is checked, then the original date stamp of any file that is copied, moved, or grafted will be preserved in the copy. If this menu item is not checked, the copy will have a date stamp of the current date and time. The status of "Copy date" is saved in the Atree. Config file upon selecting "Save" from the Configs menu. Startup args: This menu item has a submenu with four subitems consisting of the numbers 1 - 4. Selecting any of these will give you a requester which allows you to enter a string up to 80 characters long. These strings must conform to AmigaDos string path format: df0:dir1/dir/2/etc, or Volume:, or Volume:dir1/dir2/etc. The whole purpose of defining these path strings is to save them to the s:Atree.Config file so that they may be used as the default strings upon starting ATREE. To invoke the default strings, simply DO NOT include any arguments on the command line when you execute ATREE. Once having defined one or more default path strings and saved them to the config file, you may also undefine these strings by pressing alt/x keys simultaneously at each string requester, then resave the config file. If no default strings are defined in the config file, typing "run atree" without arguments on the command line will result in a string requester for you to enter one path string which will then be read into memory. File print: If checked, this item causes the output of all print routines to go to a file you name. See the "Print" option of the "Utils" menu below. This setting is saved to the config file along with so many other settings. Locate Menu: ------------------- String: Allows definition of search string specification for searching through trees for directories, or for searching through directories for files, or for searching through all files in all directories in a tree for a matching file. The definition string may contain any of the following special meaning characters: ? matches any single character * matches zero or more occurrences of characters identical to the character preceding the "*" + matches one or more occurrences of the preceding character \? matches a question mark (?) \* matches an asterisk (*) \+ matches a plus sign (+) Here are several sample strings to help you get the idea: Example Matches a??x abyx, agtx, a56x, etc. a*x x, ax, aax, aaax, etc. a?*x ajax, abthgnfdhrrhtlo666x, etc a+x ax, aax, aaax, etc. a\?x matches only "a?x" a\*x matches only "a*x" NOTE: The search string you specify will be converted to lower case and during the search process the compare string (a directory or filename) is converted to lower case so that all searches are therefore case insensitive. Also, note that a match is considered to exist if your string is determined to match only the beginning of any compare string. Thus, "abc" will match "abcdef" and "abctuq", etc. Tree: From Top: Searches from the top of the currently displayed tree for a directory matching the pattern specified through selecting "string" above. Display moves to the found directory. The search is always made downward in the display column before moving to the next column to the right. From Here: Same as above, except the search begins with the next directory down in the same column as the highlighted directory. Directory: From Top: Searches from the top of the currently highlighted directory for a file matching the pattern string. Search stops at end of list of files belonging to the highlighted directory. Display moves to found. From Here: Same as above, except search begins with the file next down from the highlighted file. All Files: From Top: Searches all files in current tree irrespective of directory for a file matching the pattern string. Search starts at top. Display moves to found. From Here: Same as above, except search begins with next file down from the currently highlighted file. Search files: This Menuitem has a submenu with four subitems: Grep string, Highlighted, Tagged, and All. The routines here add one more dimension of power to ATREE. You use the "GREP string" subitem to define a string of characters. There are powerful and flexible pattern matching options available to you in making this string. Once defined, you may then select "High- lighted", "Tagged", or "All" to systematically search the specified files in your highlighted directory for all occurrences of the defined string in each line of each file. A special window will be opened in front of the ATREE window and the the name of the file currently being searched will appear in the window title bar. Any lines containing your defined string will be printed in this window. You can stop the action by pressing any key and start the action again by pressing any key. On completion of the search of the last file, you will be informed that the search is finished and that you must press a key to get back to ATREE. GREP stands for Global Regular Expression Search and Print. ATREE was developed using the Lattice C v5.04 compiler which has a library of GREP routines especially designed to facilitate a search of files for the occurrence of strings matching defined "patterns". The routines in the Lattice library allow just about as general a set of patterns as the UNIX forms of GREP. A summary of the pattern matching possibilities and combinations is offered here. The usual "\" characters defined in K&R are supported: \n, \r, \t, \b, \\, and \xmn. Thus, "{\n" will find all occurrences of the "{" at the end of a line. And "\x41" will find all occurrences of the letter "A" in a file. And "\\" will find occurrences of "\". The "\" is also used to "escape" special characters so that they too may be searched for. The " character must be used in patterns that contain "white space", i.e. spaces or tabs. Thus, to search for the phrase, my dog has fleas, it must be included in quotes: "my dog has fleas". If you want to search files for occurrences of the " character, the pattern would be \". Brackets may be used to specify a class of characters, any ONE of which will be considered a match. Thus, "[a-z]usa" will match strings such as "ausa", "busa", "cusa", "yusa", "zusa". "[ty78eRrGg0-9]xyz" will match txyz, yxyz, 7xyz, 8xyz,...,0xyz, 1xyz, 2xyz,....,9xyz. Note that in [0-9], and [a-z], the relation 0<9 and a<z has to be observed. The "." is a wild card which will match any character except newline or end of string. : thus, ".he" matches the, The, she, She, hhe, \rhe, and .he. If you want to find 3.67, you have to type "3\.67". The "*" is used to denote "zero or more occurrences" of the character preceding it. Thus, ca*t will match ct, cat, caat, caaat, caaaat, etc. Since "." matches any character and "*" stands for any number of them, the pattern "cat.*dog" will match with any line of text containing the word "cat" followed anywhere subsequently by the word "dog". If you want to find one line quotes in your text, you can use the pattern, \".*\". The "+" character stands for "one or more occurrences of the preceding character". Thus, "ca+t" will match cat, caat, caaat, etc. The "^" is a special symbol only when used as the first character in a pattern. When so used, it causes the search to be "anchored". This means the pattern will be matched ONLY if the matching string is at the beginning of the line being searched. Thus, "^cat" will match in the line "cats are my favorite animals.", but will not match in the line "My favorite animals are cats." The "$" character functions in the reverse of the "^" and forces the match to occur only if the match string occurs at the end of the line. Thus, "cats\.$" will be found in "My favorite animals are cats." Note that if we used "cats.$" instead of "cats\.$", the "." would stand for any character. The "\" character is used to "escape" any special characters. The "!" can be used at the beginning of a character class to have the same meaning as logical "NOT" -- thus, [!a-z] matches anything other than "a" thru "z". Sort Menu: ------------------ The options in this menu should be clear -- the user can sort the highlighted directory's files by name, size, or date, and can sort the entire currently selected tree's files in all of its directories by name, size, or date. Utils Menu: ------------------ Format: Formats a disk according to the parameters set via the format option in the Configs menu. This option will present a requester asking for the volume name you wish applied to the disk. This option merely executes "format" with the RUN command -- the executable file "format" must therefore be in path, usually the path to which SYSTEM: is assigned. The correct arguments for the format command (drive to be formatted, etc.) are derived from the parameter settings in the Configs menu. You have control of Atree while the formatting is taking place. The output of the format command is printed to the CLI from which Atree was executed -- if you wish to view this CLI during formatting, you may find your CLI manually, or you may select "FRONT" from the format option in the Configs menu before starting the format process -- doing so brings the WORKBENCH screen and the CLI window into view during the formatting process. DiskCopy: This option executes the normal DiskCopy command. You specify the FROM and TO disk drives using the "From dev" and "To dev" options in the Configs menu. You will be asked for the name you wish to apply to the copy and if you don't enter anything here, the name of the copy will be the same as the name of the source disk. DO NOT set the "From dev" and the "To dev" to the same drive as this will merely waste your time copying the disk to itself. Save alt config: This option allows you to save all of your currently specified configs (colors, etc.) to a directory and file of your choice. Load alt configs: This option allows you to reload a given set of configs (colors, etc.) you previously saved to a given directory and file via the "Save alt configs" option above. Iconify: This option allows the Atree screen and window to be shut down and replaced by a very small window (not really an "icon"). This small window will always appear in the upper left hand corner of the display. It may subsequently be dragged around on the display or placed behind all other screens by clicking on the Window-to-back gadget. To reactivate Atree, just click on the word "Atree" in the small window. Sector Edit: The Atree disk sector editor. See instructions in the separate file named "SecEd.Doc" on this disk. CLI Command: Selecting this option will give you a requester. Type in any line you would ordinarily type at the CLI comandline. This line will be executed. Before the execution, however, the currently highlighted directory is made the current AmigaDos directory (just as though you had typed "cd" followed by the path of the highlighted directory). This feature was added as a convenience to the many users who spend a lot of time looking through their directories for a certain file so that they can then use it as an argument to a certain commandline, such as compile the file, or list it. Without this option, one would have to leave ATREE and find a CLI window, "cd" to the directory and then type the command line at the prompt. Print: Atree allows you to print to your printer or to a designated file all or part of a tree or just a directory. If the "File print" option of the "Configs" menu is checked, selecting any print option will give you a requester in which you are expected to enter any valid path and filename. The output of the print routines will then go to this file instead of the printer and you can subsequently use a text reader to review the file. The three options available are: Tree long: Prints all directories and files (with file size, and date). Full pathname is printed for each directory. Only first 30 characters of filename are printed. Tree short: Prints outline format of directories and files. Directories are preceded by a number representing the depth or level of the directory in the tree. For clarity, files are preceded by a "-" instead of number. Only the first 20 characters of directory and file names are printed. When the outline reaches the 18th level, subsequent levels are "wrapped" back to the left margin of the printout and continued from there. Directory: Prints the full pathname of the current directory and then prints all files (30 characters of name only), file sizes and dates. Dir Sizes: Prints a tree's directory names in outline format as above and beside each directory name, the total number of bytes in all files in the directory is printed. Atree to back: This option allows you to move the Atree screen and window to the background. It works exactly the same as selecting the ScreenToBack gadget of a screen. ********************************** Keyboard Operation ********************************** Most of the routines in Atree's menus may be accessed by first pressing the key corresponding to the first letter of the menu's name (thus, press the "t" key to access the routines in the "Tree" menu, or press the "f" key to access the routines in the "File" menu). This will cause Atree to go into a mode waiting for you to press another key -- the key you press next must be either the "escape" key, or one of the keys indicated to the right of the name of one of the routines available in the menu you have selected. Thus, if you press the "t" key, followed by the "+" key, you will activate the "Get (new)" routine of the "Tree" menu. After pressing the "t", you must press the "Esc" key to abort this mode. If a menu option has additional options, you must press the appropriate keys to access those options, or the escape key. Thus, pressing the "f", "c", and "h" keys in succession will activate the "copy highlighted file" option of the "File" menu. Pressing the"f", "c", and "t" keys will activate the "copy tagged files" option of the "File" menu. If you have pressed the "f" and "c" keys in succession and you wish to abort your operation, you must press the "Esc" key. If you have pressed the "t" key but have forgotten the keys associated with any of the options of the "Tree" menu, you may still see those options by using the mouse -- the menus can still be activated, although the options associated with them cannot. When a key corresponding to the first letter of the name of one of the menus is pressed, the window title bar will change and will indicate which menu's options Atree is now waiting for to be activated by a selection from the keyboard. As indicated above, press "Esc" to abort. ********************************* Using The Gadgets ********************************* The bottom of the Atree window has a block containing 44 gadgets. Each of these gadgets corresponds exactly to a menu item -- clicking on the gadget will do the same thing exactly as selecting the menu item. Selecting gadgets is faster than selecting menu items, so the most commonly used menu items have corresponding gadgets to make your use of Atree faster and more efficient. Below is a table that corresponds each gadget (left column) to its corresponding Menu, Menu Item, and Menu Subitem. To find out exactly what a gadget will do, find the name of the gadget in the left column below, then read across to locate the menu, item and subitem. Now find the corresponding discussion of the item or subitem under the appropriate menu heading in the section titled "Using the Atree Menus" above. ----------------------------------------------------------------------- Gadget Menu Item Subitem ----------------------------------------------------------------------- Copy All File Copy All Copy Tag File Copy Tagged Copy Hi File Copy Highlighted Move All File Move All Move Tag File Move Tagged Move Hi File Move Highlighted Del All File Delete All Del Tag File Delete Tagged Del Hi File Delete Highlighted Go 1 Directory Goto Mark 1 Go 2 Directory Goto Mark 2 Go 3 Directory Goto Mark 3 Mark 1 Directory Place Mark 1 Mark 2 Directory Place Mark 2 Mark 3 Directory Place Mark 3 Get Nxt Tree Read Next Get Rep Tree Get(replace) Get New Tree Get(new) Dir Del Directory Delete Dir Mk Directory Make Dir Rd Directory Reread Files Sort Nm Sort Directory Name Sort Sz Sort Directory Size Sort Dt Sort Directory Date File Txt File Text reader File Iff File Iff displayer File Spk File Speak Util Icn Utils Iconify Util Sed Utils Sector Edit Util CLI Utils CLI Command Erase Tree Erase Prune Directory Prune Graft Directory Graft Depth Tree Set max depth Mem Tree Show memory Info Tree Info Quick Directory Quick path Arc File Archive Highlighted Exec File Execute Show Directory Show Destination Add Tree Add from here Rep Tree Replace from here Mark Dest Directory Mark destination Go Dest Directory Goto destination